Tutorial: Create Scripts

Create Scripts

Use AppleScript to automate FoldingText and integrate with other AppleScript enabled apps.

Related:

About

FoldingText's AppleScript suite bridges to the JavaScript API.

Instead of maintaining a separate and parallel API for AppleScripts I added a single evaluate command which bridges from AppleScript to FoldingText's JavaScript API that plugins already use. This means you'll be writing all of your FoldingText specific scripting logic in JavaScript.

Getting Started

Open "AppleScript Editor" and run:

tell front document of application "FoldingText"
    evaluate script "
    function(editor, options) {
        return editor.textContent();
    }"
end tell

That uses the evaluate command to get the text content of your document. Evaluate takes a JavaScript function script parameter and evaluates it in the context of the targeted FoldingText document.

This example shows how to pass in options:

tell front document of application "FoldingText"
    evaluate script "
    function(editor, options) {
        editor.replaceSelection(
            options.start +
            editor.selectedText() +
            options.end
        );
    }" with options {start:"A", |end|:"B"}
end tell

How it works

The evaluate command works by:

  1. The passed in script string is passed into the JavaScript context and eval is used to evaluate it and the result is a JavaScript function.

  2. If you included with options those AppleScript value options are converted to a JSON string. Then passed to the JavaScript context. And then parsed to create JavaScript objects. In short the AppleScript parameters that you pass in are turned into JavaScript parameters.

  3. The eval'ed function from above is called, passing in the editor instance and options if any were provided.

  4. The results of calling that function are converted to JSON, which is then converted to AppleScript objects, which then gets passed back to your script.

Next Steps

  1. Read through the Create Plugins documentation to learn about the JavaScript API, since that's what you'll be using for any FoldingText specific scripting.

  2. Learn from existing script extensions and use them as starting points for your own solutions.

  3. Make sure to read the next section "Debugging Scripts" and use the debugger when writing your own scripts.

  4. Ask questions in the support forum.

Debugging Scripts

Use the debug suite command to debug your scripts... each of these steps is necessary to get debugging to work:

  1. Open Help > Software Development Kit

  2. Click "Run Editor" to open the editor

  3. Click the "Inspector" toolbar item to open the SDK inspector

  4. Run this script in "AppleScript Editor"

set s to "
function(editor, option) {
    debugger;
    return editor.selectedText() + option;
}"

tell application "FoldingText"
    debug script s with options "!"
end tell

Notice that this script targets the application object instead of a document. And the command name is debug instead of evaluate. The debug command is exactly the same as evaluate except it targets the SDK instead of the current document. And that means you can step through your scripts execution line by line in the debugger to figure out exactly what's going on.